Introduction

While there is no concrete and unified definition of a verifiable credential, we can say that, in the context of Self-Sovereign Identity, it consists of a digital document containing data related to a specific entity (person or thing), representing a particular situation of the subject it refers to, with the purpose of proving the truthfulness of its contents to a verifying party.

Its format consists of a JSON object containing identifiers and metadata to describe the properties of the credential, such as its issuer, validity period, representative image, a public key for verification purposes, revocation mechanisms, among others. The metadata can be signed by the issuer, ensuring that its authenticity can be verified through cryptographic verification.

Example of a Verifiable Credential

{
  "@context": [
    "https://extrimian.blob.core.windows.net/rskec/person.jsonld",
    "https://w3id.org/security/bbs/v1",
    "https://www.w3.org/2018/credentials/v1"
  ],
  "id": "8b00e43a-c4ec-451d-8b1b-95ae49357df9",
  "type": ["VerifiableCredential", "SecurityCard"],
  "credentialSubject": {
    "type": "Citizen",
    "identifier": "did:quarkid:zksync:EiBgHBYWJuMAWTRCOJpnFVEcQ4r2cPLFK9obk2qBBKMODQ"
  },
  "expirationDate": "2023-07-18T19:00:37.329Z",
  "issuanceDate": "2023-07-17T19:00:37.330Z",
  "issuer": {
    "id": "did:quarkid:zksync:EiAGpo5alPOjRDZr5o1tJsbwxapWLrudxpEJML3cxjSAQQ",
    "name": "MediCare"
  },
  "proof": {
    "type": "BbsBlsSignature2020",
    "created": "2023-07-17T19:00:57Z",
    "proofPurpose": "assertionMethod",
    "proofValue": "pllzhIz4iGjQ9GZyDGuuJWpxjtiv8V7VaaJ28Je7ttM16VHT9kgrTiKy7rfnoghyJmSZEgbMbmoURRP0yJmkF+5Rb6RW7j+exRwVndypfDNB/rZ0lrbolzuxr6bvm7HAznsGewibBG0pA8zdMyiI5g==",
    "verificationMethod": "did:quarkid:zksync:EiAGpo5alPOjRDZr5o1tJsbwxapWLrudxpEJML3cxjSAQQ#vc-bbsbls"
  }
}

Context

When two pieces of software need to exchange data, they must use a terminology that both can understand. For instance, let's consider how two people communicate. Both individuals must use the same language, and the words they use must have the same meaning for both. This could be termed as the context of a conversation.

Verifiable credentials and verifiable presentations have many attributes and values identified by URLs. However, these URLs can be long and not very user-friendly. In such cases, shorter and more user-friendly aliases can be more practical. This specification uses the "@context" property to map such aliases in the form of abbreviations to the URLs required by specific verifiable credentials and presentations.

Verifiable credentials and verifiable presentations MUST include an "@context" property. In the particular case of QuarkID, the URLs provided in this section must be processable as JSON-LD.

JSON-LD, which stands for "JSON Linked Data," is a way of representing structured data using JSON syntax while incorporating Linked Data concepts to enable semantic interoperability on the web.

Imagine we have a basic JSON-formatted verifiable credential representing information about a person's affiliation with a university:

{
  "id": "http://university.example/credentials/58473",
  "type": ["VerifiableCredential"],
  "issuer": "did:example:University1",
  "validFrom": "2010-01-01T00:00:00Z",
  "credentialSubject": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "name": "John Smith",
    "alumniOf": {
      "name": "University 1"
    }
  },
  "proof": {}
}

In this JSON, you can see information about the credential, such as the issuer, valid from date, credential subject, etc.

Now, imagine that other institutions also issue verifiable credentials, but they may use different terminologies or structures in their data.

{
  "id": "http://university.example/credentials/58473",
  "type": ["VerifiableCredential"],
  "issuer": "did:example:University2",
  "validFrom": "2010-01-01T00:00:00Z",
  "credentialSubject": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "name": "John",
    "lastName": "Smith",
    "alumniOf": {
      "name": "University 2"
    }
  },
  "proof": {}
}

In this case, the "name" property has a different interpretation compared to the first university. This is where JSON-LD comes in.

Using JSON-LD, you can add context to your data, similar to the previous example. The same JSON above can be expressed in JSON-LD as follows:

{
  "@context": [
    "https://www.w3.org/ns/credentials/v2",
    "https://www.w3.org/ns/credentials/examples/v2"
  ],
  "id": "http://university.example/credentials/58473",
  "type": ["VerifiableCredential", "ExampleAlumniCredential"],
  "issuer": "did:example:University1",
  "validFrom": "2010-01-01T00:00:00Z",
  "credentialSubject": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "name": "John Smith",
    "alumniOf": {
      "name": "University 1"
    }
  },
  "proof": {}
}

In this case, the addition of "@context" provides information about the document's context. The URLs provided in the context establish the basis for interpreting the terms used in the credential. This helps different systems understand and process credentials consistently, even if they use slightly different terminologies.

Returning to the example, thanks to the use of JSON-LD and the specification of context, verifiers will be able to understand the specific interpretation of each university and adjust their processes accordingly.

This approach allows flexibility and interoperability in handling diverse interpretations of data in different contexts, ensuring that systems can understand and verify credentials even when terminologies vary among issuers.

Differences between Contexts, Types, and Credential Schemas

This section aims to provide a comparison of the "@context," "type," and "credentialSchema" properties in the data models of verifiable credentials and verifiable presentations. It also covers some more specific use cases where these features of the data model can be utilized.

The "type" property is used to uniquely identify the type of verifiable credential, indicating what set of claims it contains. It is mandatory and is suggested to include an additional value representing the unique subtype of the credential. This property is essential to specify the nature of the information contained in the credential.

On the other hand, the "@context" property is used, from the JSON-LD perspective, to convey the meaning of the data and the definitions of terms in a machine-readable way. In a JSON representation, it remains mandatory and provides basic support for global semantics. It maps globally unique URIs to properties in verifiable credentials and presentations into shorter, more human-friendly names. This facilitates reading representations in both JSON and JSON-LD.

The "credentialSchema" property has the primary purpose of defining the structure of the verifiable credential and the data types for the values of each property. It is useful for specifying the content and structure of a set of claims in the credential. It is used to define the structure of the credential, while "@context" and JSON-LD focus on conveying semantics and term definitions.

In summary, "type" focuses on identifying the type of credential, "@context" focuses on conveying the meaning of the data in a machine-readable way, and "credentialSchema" is used to define the structure and data types of the credential. When "@context" and "credentialSchema" are combined, producers and consumers can have more confidence in the expected content and data types of the verifiable credential.

Presentation of a Verifiable Credential

Possessing a credential does not make you the subject of that credential. This is because while a verifiable credential references the issuer's keys for verification, the holder of the credential must prove ownership of the private keys associated with the DID to which the credential was issued. In this latter case, the proof is generated by cryptographically signing the presentation.

Presentations are data derived from one or more verifiable credentials, issued by one or more issuers, and shared with a specific verifier. A verifiable presentation is a tamper-proof presentation, encoded in such a way that the authorship of the data can be trusted after a process of cryptographic verification. Certain types of verifiable presentations may contain data synthesized from the original verifiable credentials but do not reveal them (e.g., zero-knowledge proofs).

In the graph presented below, you can observe the main structural differences between a verifiable credential and a verifiable presentation.

Practical example